/*
 ************************************************************************************
 * Copyright (C) 2001-2011 encuestame: system online surveys Copyright (C) 2011
 * encuestame Development Team.
 * Licensed under the Apache Software License version 2.0
 * You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
 * Unless required by applicable law or agreed to  in writing,  software  distributed
 * under the License is distributed  on  an  "AS IS"  BASIS,  WITHOUT  WARRANTIES  OR
 * CONDITIONS OF ANY KIND, either  express  or  implied.  See  the  License  for  the
 * specific language governing permissions and limitations under the License.
 ************************************************************************************
 */
package org.encuestame.oauth.security;

import org.encuestame.persistence.domain.application.ApplicationConnection;
import org.encuestame.persistence.exception.EnMeNotValidKeyOAuthSecurityException;
import org.encuestame.utils.oauth.OAuthSession;
/**
 * Implementation to manage OAuth Sessions.
 * @author Picado, Juan juanATencuestame.org
 * @since Dec 23, 2010 7:23:39 PM
 * @version $Id:$
 */
public interface OAuthSessionManager {

    /**
     * Create a new OAuth session for the application with the assigned api key.
     * @param apiKey the api key, assumed to be valid by the time this method is invoked.
     * @param callbackUrl the URL the client wants you to redirect the user to after he or she authorizes the connection
     * @return a new OAuthSession containing an assigned request token
     */
    OAuthSession newOAuthSession(String apiKey, String callbackUrl);

    /**
     * Get the active OAuthSession indexed by the assigned request token.
     * @param requestToken the request token
     * @throws InvalidRequestTokenException if the request token is not valid; this could happen if the session has completed or expired.
     */
    OAuthSession getSession(String requestToken) throws EnMeNotValidKeyOAuthSecurityException;

    /**
     * Record that a user granted access to the application associated with the OAuthSession.
     * @param requestToken the request token that identifies the OAuthSession
     * @param authorizingAccountId the id of the user account that authorized the connection
     * @param verifier the verifier token generated by the OAuthProvider; expected to be submitted by the client on the accessToken request that follows the callback redirect.
     * @return the updated OAuthSession reflecting authorized() status
     * @throws InvalidRequestTokenException if the request token is not valid; this could happen if the session has completed or expired.
     * @throws EnMeNotValidKeyOAuthSecurityException
     */
    OAuthSession authorize(String requestToken, Long authorizingAccountId, String verifier) throws  EnMeNotValidKeyOAuthSecurityException;

    /**
     * For the OAuthSession identified by the requestToken, grant the application identified by the {@link OAuthSession#getApiKey()} access to the
     * {@link OAuthSession#getAuthorizingAccountId() authorizing member account}.
     * An access token will be assigned and returned in the AppConnection object.
     * @throws InvalidRequestTokenException if the request token is not valid; this could happen if the session has completed or expired.
     */
    ApplicationConnection grantAccess(String requestToken) throws EnMeNotValidKeyOAuthSecurityException;

}
